<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Rendering Individual Decorators - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/learning.form.decorators.individual.html">Inglês (English)</a></li>
    <li><a href="../pt-br/learning.form.decorators.individual.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="learning.form.decorators.layering.html">Layering Decorators</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="learning.form.decorators.html">Understanding and Using Zend Form Decorators</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="learning.form.decorators.composite.html">Creating and Rendering Composite Elements</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="learning.form.decorators.individual" class="section"><div class="info"><h1 class="title">Rendering Individual Decorators</h1></div>
    

    <p class="para">
        In the <a href="learning.form.decorators.layering.html" class="link">previous section</a>, we
        looked at how you can combine decorators to create complex output. We noted that while you
        have a ton of flexibility with this approach, it also adds some complexity and overhead. In
        this section, we will examine how to render decorators individually in order to create
        custom markup for forms and/or individual elements.
    </p>

    <p class="para">
        Once you have registered your decorators, you can later retrieve them by name from the
        element. Let&#039;s review the previous example:
    </p>

    <pre class="programlisting brush: php">
$element = new Zend_Form_Element(&#039;foo&#039;, array(
    &#039;label&#039;      =&gt; &#039;Foo&#039;,
    &#039;belongsTo&#039;  =&gt; &#039;bar&#039;,
    &#039;value&#039;      =&gt; &#039;test&#039;,
    &#039;prefixPath&#039; =&gt; array(&#039;decorator&#039; =&gt; array(
        &#039;My_Decorator&#039; =&gt; &#039;path/to/decorators/&#039;,
    )),
    &#039;decorators&#039; =&gt; array(
        &#039;SimpleInput&#039;
        array(&#039;SimpleLabel&#039;, array(&#039;placement&#039; =&gt; &#039;append&#039;)),
    ),
));
</pre>


    <p class="para">
        If we wanted to pull and render just the <span class="classname">SimpleInput</span> decorator, we
        can do so using the  <span class="methodname">getDecorator()</span> method:
    </p>

    <pre class="programlisting brush: php">
$decorator = $element-&gt;getDecorator(&#039;SimpleInput&#039;);
echo $decorator-&gt;render(&#039;&#039;);
</pre>


    <p class="para">
        This is pretty easy, but it can be made even easier; let&#039;s do it in a single line:
    </p>

    <pre class="programlisting brush: php">
echo $element-&gt;getDecorator(&#039;SimpleInput&#039;)-&gt;render(&#039;&#039;);
</pre>


    <p class="para">
        Not too bad, but still a little complex. To make this easier, a shorthand notation was
        introduced into <span class="classname">Zend_Form</span> in 1.7: you can render any registered
        decorator by calling a method of the format  <span class="methodname">renderDecoratorName()</span>.
        This will effectively perform what you see above, but makes the <var class="varname">$content</var>
        argument optional and simplifies the usage:
    </p>

    <pre class="programlisting brush: php">
echo $element-&gt;renderSimpleInput();
</pre>


    <p class="para">
        This is a neat trick, but how and why would you use it?
    </p>

    <p class="para">
        Many developers and designers have very precise markup needs for their forms. They would
        rather have full control over the output than rely on a more automated solution which may or
        may not conform to their design. In other cases, the form layout may require a lot of
        specialized markup -- grouping arbitrary elements, making some invisible unless a particular
        link is selected, etc.
    </p>

    <p class="para">
        Let&#039;s utilize the ability to render individual decorators to create some specialized markup.
    </p>

    <p class="para">
        First, let&#039;s define a form. Our form will capture a user&#039;s demographic details. The markup
        will be highly customized, and in some cases use view helpers directly instead of form
        elements in order to achieve its goals. Here is the basic form definition:
    </p>

    <pre class="programlisting brush: php">
class My_Form_UserDemographics extends Zend_Form
{
    public function init()
    {
        // Add a path for my own decorators
        $this-&gt;addElementPrefixPaths(array(
            &#039;decorator&#039; =&gt; array(&#039;My_Decorator&#039; =&gt; &#039;My/Decorator&#039;),
        ));

        $this-&gt;addElement(&#039;text&#039;, &#039;firstName&#039;, array(
            &#039;label&#039; =&gt; &#039;First name: &#039;,
        ));
        $this-&gt;addElement(&#039;text&#039;, &#039;lastName&#039;, array(
            &#039;label&#039; =&gt; &#039;Last name: &#039;,
        ));
        $this-&gt;addElement(&#039;text&#039;, &#039;title&#039;, array(
            &#039;label&#039; =&gt; &#039;Title: &#039;,
        ));
        $this-&gt;addElement(&#039;text&#039;, &#039;dateOfBirth&#039;, array(
            &#039;label&#039; =&gt; &#039;Date of Birth (DD/MM/YYYY): &#039;,
        ));
        $this-&gt;addElement(&#039;text&#039;, &#039;email&#039;, array(
            &#039;label&#039; =&gt; &#039;Your email address: &#039;,
        ));
        $this-&gt;addElement(&#039;password&#039;, &#039;password&#039;, array(
            &#039;label&#039; =&gt; &#039;Password: &#039;,
        ));
        $this-&gt;addElement(&#039;password&#039;, &#039;passwordConfirmation&#039;, array(
            &#039;label&#039; =&gt; &#039;Confirm Password: &#039;,
        ));
    }
}
</pre>


    <blockquote class="note"><p><b class="note">Note</b>: 
        <p class="para">
            We&#039;re not defining any validators or filters at this time, as they are not relevant to
            the discussion of decoration. In a real-world scenario, you should define them.
        </p>
    </p></blockquote>

    <p class="para">
        With that out of the way, let&#039;s consider how we might want to display this form. One common
        idiom with first/last names is to display them on a single line; when a title is provided,
        that is often on the same line as well. Dates, when not using a JavaScript date chooser,
        will often be separated into three fields displayed side by side.
    </p>

    <p class="para">
        Let&#039;s use the ability to render an element&#039;s decorators one by one to accomplish this.
        First, let&#039;s note that no explicit decorators were defined for the given elements. As a
        refresher, the default decorators for (most) elements are:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                <span class="classname">ViewHelper</span>: utilize a view helper to render a form input
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <span class="classname">Errors</span>: utilize the <span class="classname">FormErrors</span> view
                helper to render validation errors
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <span class="classname">Description</span>: utilize the <span class="classname">FormNote</span> view
                helper to render the element description (if any)
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <span class="classname">HtmlTag</span>: wrap the above three items in a
                <em class="emphasis">&lt;dd&gt;</em> tag
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <span class="classname">Label</span>: render the element label using the
                <span class="classname">FormLabel</span> view helper (and wrap it in a
                <em class="emphasis">&lt;dt&gt;</em> tag)
            </p>
        </li>
    </ul>

    <p class="para">
        Also, as a refresher, you can access any element of a form as if it were a class property;
        simply reference the element by the name you assigned it.
    </p>

    <p class="para">
        Our view script might then look like this:
    </p>

    <pre class="programlisting brush: php">
&lt;?php
$form = $this-&gt;form;
// Remove &lt;dt&gt; from label generation
foreach ($form-&gt;getElements() as $element) {
    $element-&gt;getDecorator(&#039;label&#039;)-&gt;setOption(&#039;tag&#039;, null);
}
?&gt;
&lt;form method=&quot;&lt;?php echo $form-&gt;getMethod() ?&gt;&quot; action=&quot;&lt;?php echo
    $form-&gt;getAction()?&gt;&quot;&gt;
    &lt;div class=&quot;element&quot;&gt;
        &lt;?php echo $form-&gt;title-&gt;renderLabel()
              . $form-&gt;title-&gt;renderViewHelper() ?&gt;
        &lt;?php echo $form-&gt;firstName-&gt;renderLabel()
              . $form-&gt;firstName-&gt;renderViewHelper() ?&gt;
        &lt;?php echo $form-&gt;lastName-&gt;renderLabel()
              . $form-&gt;lastName-&gt;renderViewHelper() ?&gt;
    &lt;/div&gt;
    &lt;div class=&quot;element&quot;&gt;
        &lt;?php echo $form-&gt;dateOfBirth-&gt;renderLabel() ?&gt;
        &lt;?php echo $this-&gt;formText(&#039;dateOfBirth[day]&#039;, &#039;&#039;, array(
            &#039;size&#039; =&gt; 2, &#039;maxlength&#039; =&gt; 2)) ?&gt;
        /
        &lt;?php echo $this-&gt;formText(&#039;dateOfBirth[month]&#039;, &#039;&#039;, array(
            &#039;size&#039; =&gt; 2, &#039;maxlength&#039; =&gt; 2)) ?&gt;
        /
        &lt;?php echo $this-&gt;formText(&#039;dateOfBirth[year]&#039;, &#039;&#039;, array(
            &#039;size&#039; =&gt; 4, &#039;maxlength&#039; =&gt; 4)) ?&gt;
    &lt;/div&gt;
    &lt;div class=&quot;element&quot;&gt;
        &lt;?php echo $form-&gt;password-&gt;renderLabel()
              . $form-&gt;password-&gt;renderViewHelper() ?&gt;
    &lt;/div&gt;
    &lt;div class=&quot;element&quot;&gt;
        &lt;?php echo $form-&gt;passwordConfirmation-&gt;renderLabel()
              . $form-&gt;passwordConfirmation-&gt;renderViewHelper() ?&gt;
    &lt;/div&gt;
    &lt;?php echo $this-&gt;formSubmit(&#039;submit&#039;, &#039;Save&#039;) ?&gt;
&lt;/form&gt;
</pre>


    <p class="para">
        If you use the above view script, you&#039;ll get approximately the following
        <acronym class="acronym">HTML</acronym> (approximate, as the <acronym class="acronym">HTML</acronym> below is formatted):
    </p>

    <pre class="programlisting brush: html">
&lt;form method=&quot;post&quot; action=&quot;&quot;&gt;
    &lt;div class=&quot;element&quot;&gt;
        &lt;label for=&quot;title&quot; tag=&quot;&quot; class=&quot;optional&quot;&gt;Title:&lt;/label&gt;
        &lt;input type=&quot;text&quot; name=&quot;title&quot; id=&quot;title&quot; value=&quot;&quot;/&gt;

        &lt;label for=&quot;firstName&quot; tag=&quot;&quot; class=&quot;optional&quot;&gt;First name:&lt;/label&gt;
        &lt;input type=&quot;text&quot; name=&quot;firstName&quot; id=&quot;firstName&quot; value=&quot;&quot;/&gt;

        &lt;label for=&quot;lastName&quot; tag=&quot;&quot; class=&quot;optional&quot;&gt;Last name:&lt;/label&gt;
        &lt;input type=&quot;text&quot; name=&quot;lastName&quot; id=&quot;lastName&quot; value=&quot;&quot;/&gt;
    &lt;/div&gt;

    &lt;div class=&quot;element&quot;&gt;
        &lt;label for=&quot;dateOfBirth&quot; tag=&quot;&quot; class=&quot;optional&quot;&gt;Date of Birth
            (DD/MM/YYYY):&lt;/label&gt;
        &lt;input type=&quot;text&quot; name=&quot;dateOfBirth[day]&quot; id=&quot;dateOfBirth-day&quot;
            value=&quot;&quot; size=&quot;2&quot; maxlength=&quot;2&quot;/&gt;
        /
        &lt;input type=&quot;text&quot; name=&quot;dateOfBirth[month]&quot; id=&quot;dateOfBirth-month&quot;
            value=&quot;&quot; size=&quot;2&quot; maxlength=&quot;2&quot;/&gt;
        /
        &lt;input type=&quot;text&quot; name=&quot;dateOfBirth[year]&quot; id=&quot;dateOfBirth-year&quot;
            value=&quot;&quot; size=&quot;4&quot; maxlength=&quot;4&quot;/&gt;
    &lt;/div&gt;

    &lt;div class=&quot;element&quot;&gt;
        &lt;label for=&quot;password&quot; tag=&quot;&quot; class=&quot;optional&quot;&gt;Password:&lt;/label&gt;
        &lt;input type=&quot;password&quot; name=&quot;password&quot; id=&quot;password&quot; value=&quot;&quot;/&gt;
    &lt;/div&gt;

    &lt;div class=&quot;element&quot;&gt;
        &lt;label for=&quot;passwordConfirmation&quot; tag=&quot;&quot; class=&quot;&quot; id=&quot;submit&quot;
            value=&quot;Save&quot;/&gt;
&lt;/form&gt;
</pre>


    <p class="para">
        It may not be truly pretty, but with some CSS, it could be made to look exactly how you
        might want to see it. The main point, however, is that this form was generated using almost
        entirely custom markup, while still leveraging decorators for the most common markup (and to
        ensure things like escaping with htmlentities and value injection occur).
    </p>

    <p class="para">
        By this point in the tutorial, you should be getting fairly comfortable with the markup
        possibilities using <span class="classname">Zend_Form</span>&#039;s decorators. In the next section,
        we&#039;ll revisit the date element from above, and demonstrate how to create a custom element
        and decorator for composite elements.
    </p>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="learning.form.decorators.layering.html">Layering Decorators</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="learning.form.decorators.html">Understanding and Using Zend Form Decorators</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="learning.form.decorators.composite.html">Creating and Rendering Composite Elements</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="learning.html">Learning Zend Framework</a></li>
  <li class="header up"><a href="learning.form.decorators.html">Understanding and Using Zend Form Decorators</a></li>
  <li><a href="learning.form.decorators.intro.html">Introduction</a></li>
  <li><a href="learning.form.decorators.simplest.html">Decorator Basics</a></li>
  <li><a href="learning.form.decorators.layering.html">Layering Decorators</a></li>
  <li class="active"><a href="learning.form.decorators.individual.html">Rendering Individual Decorators</a></li>
  <li><a href="learning.form.decorators.composite.html">Creating and Rendering Composite Elements</a></li>
  <li><a href="learning.form.decorators.conclusion.html">Conclusion</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>